Skip to main content
Version: Latest (Core: 0.60.x, Azure: 0.46.x)

Generated Types

This page documents what type definitions in TypeSpec are generated as in emitted libraries

Models​

Flattening​

NOTE: Flattening is NOT a recommended pattern, and you shouldn't use it unless told by SDK architects.

model Properties {
  name: string;
}

model Foo {
  @flattenProperty
  prop: Properties;
}

Models with additional properties​

Additional properties of any type​

Recommend usage:

model Animal {
  name: string;
  kind: string;
  ...Record<unknown>;
}

Other usages:

model Animal extends Record<unknown> {
  name: string;
  kind: string;
}
model Animal is Record<unknown> {
  name: string;
  kind: string;
}

Additional properties of specific type​

model AnimalProperty {
  category: string;
  value: unknown;
}

model Animal {
  name: string;
  kind: string;
  ...Record<AnimalProperty>;
}

Additional properties of union type​

model Animal {
  name: string;
  kind: string;
  ...Record<string | int32>;
}
model Animal {
  name: string;
  kind: string;
  ...Record<string>;
  ...Record<int32>;
}

Additional properties of nullable type​

model Animal {
  name: string;
  kind: string;
  ...Record<string | null>;
}

Nullable​

TypeSpec uses | null to represent nullable types. Nullability is handled differently in languages, but emitter authors will find information about nullability by inspecting the type of a property.

model Foo {
  basicNullableProperty: string | null;
  modelNullableProperty: Bar | null;
  unionNullableProperty: Bar | Baz | null;
  enumNullableProperty: LR | null;
}

model Bar {
  prop: string;
}

model Baz {
  prop: int32;
}

enum LR {
  left,
  right,
}

Unions​

Union of literals with same type​

All emitters will generate their version of a closed enum.

union LR {
  left: "left",
  right: "right",
}

Inline union of literals with same type​

This is union defined inline at point of usage.

model Widget {
  horizontal: "left" | "right";
}

Union of basic type and literals of that type​

Each language will generate their version of an open enum.

union Colors {
  string,
  red: "red",
  blue: "blue",
}

Inline union of basic type and literals of that type​

This is union defined inline at point of usage which include the base type as an option.

model Widget {
  color: "red" | "blue" | string;
}

Union of other union/enum, basic type and literals of that type​

import "@azure-tools/typespec-azure-resource-manager";

union ProvisioningState {
  string,
  "InProgress",
  Azure.ResourceManager.ResourceProvisioningState,
}

Union of other unions of literals with same type​

union LR {
  left: "left",
  right: "right",
}

union UD {
  up: "up",
  down: "down",
}

union Orientation {
  LR,
  UD,
}

Inline union of other unions of literals with same type​

union LR {
  left: "left",
  right: "right",
}

union UD {
  up: "up",
  down: "down",
}

model Widget {
  orientation: LR | UD;
}

Union with multiple types​

These are unions where the values don't share same type.

model Shirt {
  sizing: 32 | 34 | int32 | "small" | "medium" | string;
}

Enums​

Standard​

Standard enums will be generated as closed enums.

enum LR {
  left,
  right,
}

Versioning Enums​

@versioned(Versions)
@service
namespace My.Service;

enum Versions {
  v1,
  v2,
}

Spread​

Spreading enums will return the resultant enum as a new single closed enum.

enum LR {
  left,
  right,
}

enum UD {
  up,
  down,
}

enum Orientation {
  ...LR,
  ...UD,
}

Scalars​

Encoding​

We will take the @encode decorator into account, determining how we serialize inputted scalars to send over the wire.

model Test {
  @encode(DateTimeKnownEncoding.rfc3339)
  prop: utcDateTime;
}

When you specify an encoding type, say that you want to encode an integer as a string, that will also be represented in our generated SDKs.

model Test {
  @encode(string)
  prop: int64;
}